How Do I Reference Images in my HTML Output Instead of Embedding in Java Engine?

When outputting to HTML, users have the option of having images being output in their template via an Import Tag being embedded into the output as BASE64 encoded images, or they can leave the images as file locations pointing to the image source. This article teaches how to explicitly specify one output method or the other.

Default Behavior#

The template used in all the examples bellow is an import tag importing an image from a URL.

The following code snippet shows our default behavior:

File fileReport = new File("out/report_default.html");
FileInputStream template = new FileInputStream("data/image.docx");
FileOutputStream reportStream = new FileOutputStream(fileReport);
ProcessHtmlAPI report = new ProcessHtml(template, reportStream);
            
// Nothing specified yet
         
report.processSetup();
          
DataSourceProvider datasource = new SaxonDataSource(new FileInputStream("data/images.xml"));
            
report.processData(datasource, "images");
            
report.processComplete();
template.close();
reportStream.close();    

This code creates the following HTML output. You can see that the images default to being embedded inside the HTML as BASE64 encoded images:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
 "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="Content-Language" content="en">
<style type="text/css">
p {
font-family:Calibri;
font-size:11.0pt;
color:#000000;
margin-top:0.0pt;
margin-bottom:8.0pt;
line-height:1.08;
margin-right:0.0pt;
border:0 none;
text-align:left;
text-indent:0.0pt;
}
IMG.centered{
    display: block;
    margin-left: auto;
    margin-right: auto
}IMG.right{
    float:right;
}IMG.left{
    float:left;
}
#container {
    width:624px;
    margin:0px auto;
}
</style>
</head>
<body><div id="container">
<p><br><img src="data:image/png;base64,/9j[...]42Q==" width="1024" height="768" /><br></p>
</div></body>
</html>

The same default output can be achieved by explicitly specifying to embed the images in the output using the setEmbedImages method:

File fileReport = new File("out/report_true.html");
FileInputStream template = new FileInputStream("data/image.docx");
FileOutputStream reportStream = new FileOutputStream(fileReport);
ProcessHtmlAPI report = new ProcessHtml(template, reportStream);

// Explicitly specify to embed images in output
report.setEmbedImages(true);

report.processSetup();

DataSourceProvider datasource = new SaxonDataSource(new FileInputStream("data/images.xml"));

report.processData(datasource, "images");

report.processComplete();
template.close();
reportStream.close();

Referencing Image Locations in HTML Output#

Alternatively, the user can specify a location for the images to be saved as output is generated, and then these image locations can be referenced in the HTML. To do this, the user needs to use two methods:

ProcessHtmlAPI.setImagePath(String s, String s2, String s3): this will allow the user to specify relative the location to save the images, and the relative location to the output HTML to reference the images, as well as the prefix to use for the image. Read more here.
ProcessHtmlAPI.setEmbedImages(Boolean b): This is the same method used above to specify the default functionality of embedding the images. Setting this to false will use the specified image paths to save and reference the images. Read more here.

The final code looks like this:

File fileReport = new File("out/report_false.html");
FileInputStream template = new FileInputStream("data/image.docx");
FileOutputStream reportStream = new FileOutputStream(fileReport);
ProcessHtmlAPI report = new ProcessHtml(template, reportStream);

// Specify to use file reference instead of embedding images.
// Save images to the relative path "out/images"
// Since the HTML output is to the relative path "out" the relative image location to the HTML file is just "images"
// Prefix the saved image names with "outputImage"
report.setImagePath("out/images", "images", "outputImage");
// Explicitly override default functionality
report.setEmbedImages(false);

report.processSetup();

DataSourceProvider datasource = new SaxonDataSource(new FileInputStream("data/images.xml"));

report.processData(datasource, "images");

report.processComplete();
template.close();
reportStream.close();

The output HTML references the image at the relative "images" location, and the image is saved with our specified prefix and an appended identifier:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
 "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="Content-Language" content="en">
<style type="text/css">
p {
font-family:Calibri;
font-size:11.0pt;
color:#000000;
margin-top:0.0pt;
margin-bottom:8.0pt;
line-height:1.08;
margin-right:0.0pt;
border:0 none;
text-align:left;
text-indent:0.0pt;
}
IMG.centered{
    display: block;
    margin-left: auto;
    margin-right: auto
}IMG.right{
    float:right;
}IMG.left{
    float:left;
}
#container {
    width:624px;
    margin:0px auto;
}
</style>
</head>
<body><div id="container">
<p><br><img src="images/outputImage1724012377056703473.jpg" width="1024" height="768" /><br></p>
</div></body>
</html>